/*
 * Copyright (c) 2000, 2013, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */


package java.util.logging;

import java.io.UnsupportedEncodingException;

/**
 * A <tt>Handler</tt> object takes log messages from a <tt>Logger</tt> and
 * exports them.  It might for example, write them to a console
 * or write them to a file, or send them to a network logging service,
 * or forward them to an OS log, or whatever.
 * <p>
 * A <tt>Handler</tt> can be disabled by doing a <tt>setLevel(Level.OFF)</tt>
 * and can  be re-enabled by doing a <tt>setLevel</tt> with an appropriate level.
 * <p>
 * <tt>Handler</tt> classes typically use <tt>LogManager</tt> properties to set
 * default values for the <tt>Handler</tt>'s <tt>Filter</tt>, <tt>Formatter</tt>,
 * and <tt>Level</tt>.  See the specific documentation for each concrete
 * <tt>Handler</tt> class.
 *
 * @since 1.4
 */

public abstract class Handler {

  private static final int offValue = Level.OFF.intValue();
  private final LogManager manager = LogManager.getLogManager();

  // We're using volatile here to avoid synchronizing getters, which
  // would prevent other threads from calling isLoggable()
  // while publish() is executing.
  // On the other hand, setters will be synchronized to exclude concurrent
  // execution with more complex methods, such as StreamHandler.publish().
  // We wouldn't want 'level' to be changed by another thread in the middle
  // of the execution of a 'publish' call.
  private volatile Filter filter;
  private volatile Formatter formatter;
  private volatile Level logLevel = Level.ALL;
  private volatile ErrorManager errorManager = new ErrorManager();
  private volatile String encoding;

  // Package private support for security checking.  When sealed
  // is true, we access check updates to the class.
  boolean sealed = true;

  /**
   * Default constructor.  The resulting <tt>Handler</tt> has a log
   * level of <tt>Level.ALL</tt>, no <tt>Formatter</tt>, and no
   * <tt>Filter</tt>.  A default <tt>ErrorManager</tt> instance is installed
   * as the <tt>ErrorManager</tt>.
   */
  protected Handler() {
  }

  /**
   * Publish a <tt>LogRecord</tt>.
   * <p>
   * The logging request was made initially to a <tt>Logger</tt> object,
   * which initialized the <tt>LogRecord</tt> and forwarded it here.
   * <p>
   * The <tt>Handler</tt>  is responsible for formatting the message, when and
   * if necessary.  The formatting should include localization.
   *
   * @param record description of the log event. A null record is silently ignored and is not
   * published
   */
  public abstract void publish(LogRecord record);

  /**
   * Flush any buffered output.
   */
  public abstract void flush();

  /**
   * Close the <tt>Handler</tt> and free all associated resources.
   * <p>
   * The close method will perform a <tt>flush</tt> and then close the
   * <tt>Handler</tt>.   After close has been called this <tt>Handler</tt>
   * should no longer be used.  Method calls may either be silently
   * ignored or may throw runtime exceptions.
   *
   * @throws SecurityException if a security manager exists and if the caller does not have
   * <tt>LoggingPermission("control")</tt>.
   */
  public abstract void close() throws SecurityException;

  /**
   * Set a <tt>Formatter</tt>.  This <tt>Formatter</tt> will be used
   * to format <tt>LogRecords</tt> for this <tt>Handler</tt>.
   * <p>
   * Some <tt>Handlers</tt> may not use <tt>Formatters</tt>, in
   * which case the <tt>Formatter</tt> will be remembered, but not used.
   * <p>
   *
   * @param newFormatter the <tt>Formatter</tt> to use (may not be null)
   * @throws SecurityException if a security manager exists and if the caller does not have
   * <tt>LoggingPermission("control")</tt>.
   */
  public synchronized void setFormatter(Formatter newFormatter) throws SecurityException {
    checkPermission();
    // Check for a null pointer:
    newFormatter.getClass();
    formatter = newFormatter;
  }

  /**
   * Return the <tt>Formatter</tt> for this <tt>Handler</tt>.
   *
   * @return the <tt>Formatter</tt> (may be null).
   */
  public Formatter getFormatter() {
    return formatter;
  }

  /**
   * Set the character encoding used by this <tt>Handler</tt>.
   * <p>
   * The encoding should be set before any <tt>LogRecords</tt> are written
   * to the <tt>Handler</tt>.
   *
   * @param encoding The name of a supported character encoding. May be null, to indicate the
   * default platform encoding.
   * @throws SecurityException if a security manager exists and if the caller does not have
   * <tt>LoggingPermission("control")</tt>.
   * @throws UnsupportedEncodingException if the named encoding is not supported.
   */
  public synchronized void setEncoding(String encoding)
      throws SecurityException, java.io.UnsupportedEncodingException {
    checkPermission();
    if (encoding != null) {
      try {
        if (!java.nio.charset.Charset.isSupported(encoding)) {
          throw new UnsupportedEncodingException(encoding);
        }
      } catch (java.nio.charset.IllegalCharsetNameException e) {
        throw new UnsupportedEncodingException(encoding);
      }
    }
    this.encoding = encoding;
  }

  /**
   * Return the character encoding for this <tt>Handler</tt>.
   *
   * @return The encoding name.  May be null, which indicates the default encoding should be used.
   */
  public String getEncoding() {
    return encoding;
  }

  /**
   * Set a <tt>Filter</tt> to control output on this <tt>Handler</tt>.
   * <P>
   * For each call of <tt>publish</tt> the <tt>Handler</tt> will call
   * this <tt>Filter</tt> (if it is non-null) to check if the
   * <tt>LogRecord</tt> should be published or discarded.
   *
   * @param newFilter a <tt>Filter</tt> object (may be null)
   * @throws SecurityException if a security manager exists and if the caller does not have
   * <tt>LoggingPermission("control")</tt>.
   */
  public synchronized void setFilter(Filter newFilter) throws SecurityException {
    checkPermission();
    filter = newFilter;
  }

  /**
   * Get the current <tt>Filter</tt> for this <tt>Handler</tt>.
   *
   * @return a <tt>Filter</tt> object (may be null)
   */
  public Filter getFilter() {
    return filter;
  }

  /**
   * Define an ErrorManager for this Handler.
   * <p>
   * The ErrorManager's "error" method will be invoked if any
   * errors occur while using this Handler.
   *
   * @param em the new ErrorManager
   * @throws SecurityException if a security manager exists and if the caller does not have
   * <tt>LoggingPermission("control")</tt>.
   */
  public synchronized void setErrorManager(ErrorManager em) {
    checkPermission();
    if (em == null) {
      throw new NullPointerException();
    }
    errorManager = em;
  }

  /**
   * Retrieves the ErrorManager for this Handler.
   *
   * @return the ErrorManager for this Handler
   * @throws SecurityException if a security manager exists and if the caller does not have
   * <tt>LoggingPermission("control")</tt>.
   */
  public ErrorManager getErrorManager() {
    checkPermission();
    return errorManager;
  }

  /**
   * Protected convenience method to report an error to this Handler's
   * ErrorManager.  Note that this method retrieves and uses the ErrorManager
   * without doing a security check.  It can therefore be used in
   * environments where the caller may be non-privileged.
   *
   * @param msg a descriptive string (may be null)
   * @param ex an exception (may be null)
   * @param code an error code defined in ErrorManager
   */
  protected void reportError(String msg, Exception ex, int code) {
    try {
      errorManager.error(msg, ex, code);
    } catch (Exception ex2) {
      System.err.println("Handler.reportError caught:");
      ex2.printStackTrace();
    }
  }

  /**
   * Set the log level specifying which message levels will be
   * logged by this <tt>Handler</tt>.  Message levels lower than this
   * value will be discarded.
   * <p>
   * The intention is to allow developers to turn on voluminous
   * logging, but to limit the messages that are sent to certain
   * <tt>Handlers</tt>.
   *
   * @param newLevel the new value for the log level
   * @throws SecurityException if a security manager exists and if the caller does not have
   * <tt>LoggingPermission("control")</tt>.
   */
  public synchronized void setLevel(Level newLevel) throws SecurityException {
    if (newLevel == null) {
      throw new NullPointerException();
    }
    checkPermission();
    logLevel = newLevel;
  }

  /**
   * Get the log level specifying which messages will be
   * logged by this <tt>Handler</tt>.  Message levels lower
   * than this level will be discarded.
   *
   * @return the level of messages being logged.
   */
  public Level getLevel() {
    return logLevel;
  }

  /**
   * Check if this <tt>Handler</tt> would actually log a given <tt>LogRecord</tt>.
   * <p>
   * This method checks if the <tt>LogRecord</tt> has an appropriate
   * <tt>Level</tt> and  whether it satisfies any <tt>Filter</tt>.  It also
   * may make other <tt>Handler</tt> specific checks that might prevent a
   * handler from logging the <tt>LogRecord</tt>. It will return false if
   * the <tt>LogRecord</tt> is null.
   * <p>
   *
   * @param record a <tt>LogRecord</tt>
   * @return true if the <tt>LogRecord</tt> would be logged.
   */
  public boolean isLoggable(LogRecord record) {
    final int levelValue = getLevel().intValue();
    if (record.getLevel().intValue() < levelValue || levelValue == offValue) {
      return false;
    }
    final Filter filter = getFilter();
    if (filter == null) {
      return true;
    }
    return filter.isLoggable(record);
  }

  // Package-private support method for security checks.
  // If "sealed" is true, we check that the caller has
  // appropriate security privileges to update Handler
  // state and if not throw a SecurityException.
  void checkPermission() throws SecurityException {
    if (sealed) {
      manager.checkPermission();
    }
  }
}
